Tech Arsenal 1

home *** CD-ROM | disk | FTP | other *** search

/ Tech Arsenal 1 / Tech Arsenal (Arsenal Computer).ISO / tek-04 / uldial.zip / ULDIAL.DOC < prev next >

Wrap

Text File | 1990-07-12 | 19KB | 439 lines

╔════════════════════════════════════════════════════════════════╗ ║ Dialog Objects as Enhancements to Turbo Power OOP Professional ║ ║ New Communications Technology, Inc. ║ ║ Version 2.0 ║ ║ by John Poindexter ║ ║ CIS 73717,3405 ║ ║ July 12, 1990 ║ ║ ┌───────┐┌────────┐ ║ ║ │ Ok ││ Cancel │ ║ ║ └───────┘└────────┘ ║ ╚════════════════════════════════════════════════════════════════╝ Version 2.0 of this unit makes some major improvements in encapsulating the details of the radio buttons and providing more flexibility in the instantiation of dialog boxes. The main object of this unit is DialogBox, an object to display short messages or instructions, get user input if desired and exit using radio buttons. There is also a timeout provision so the box can be used for temporary messages that are to be displayed for a short period of time and then clear. The above logo is a simulation of what you will get. The new object RadioButtons is self contained and may be used in situations other than DialogBox. Object hierarchy: [Root] [Root] [Root] DialogBox [AbstractWindow] [StringArray] [RawWindow] MStringArray [StackWindow] [CommandWindow] [AbstractSelector] EntryScreen [PickList] RadioButtons DialogBox although an immediate descendant of Root contains an EntryScreenPtr field and RadioButtonsPtr fields and uses MStringArray which adds a data field and method that keep track of the maximum string length of added strings. DialogBox has an automatic sizing feature which is the reason for making it an immediate descendant of Root rather than EntryScreen. The minimal statements to use DialogBox look like this: if not MyDialog.Init(rbHoriz,1,30,2,20) then Exit; with MyDialog do begin AddMessageString('This is a test of DialogBox.'); AddChoiceString('Ok Cancel'); AddHeader(' My Test ', heTC); Process; Code := GetLastChoice; Done; end; Unit ULDial uses Unit ULRoot which is included in the archive. TESTDIAL.EXE is an interactive testing program that will give you an opportunity to try out DialogBox. Types. ====== HorizVerticalType = (rbHoriz, rbVertical); Constants. ========== ucULDial = 201 Unit code for Unit ULDial. scOk = 0 scCancel = 1 scRetry = 2 scTimeOut = 99 Status codes which may be used for exit status of DialogBox. Variables. ========== ULRootColorSet : ColorSet This is initialized to ULColorSet which is in ULRoot. ButtonFrame : FrameArray This is initialized to SglWindowFrame in ULDial. Miscellaneous error codes and error messages are in ULRoot. Objects. ======== MStringArrayPtr = ^MStringArray MStringArray = object(StringArray) msMaxLen : byte; ... function AddMString(St : string): word; function GetMaxLen: byte; end; RadioButtonsPtr = ^RadioButtons RadioButtons = object(PickList) rbChoices : MStringArrayPtr; rbOrient : HorizVerticalType; ... constructor Init(); destructor Done; virtual; procedure ItemString(); virtual; procedure ProcessSelf; virtual; end; DialogBoxPtr = ^DialogBox; DialogBox = object(Root) dlText : MStringArrayPtr; dlChoices : MStringArrayPtr; dlEntry : EntryScreenPtr; dlButtons : RadioButtonsPtr; ... constructor Init(); constructor InitDeluxe(); destructor Done; virtual; procedure Clear; function GetLastError: word; procedure Process; virtual; procedure AddMessageString(Msg: string); procedure AddChoiceString(Choice: string); procedure AddChoice(Choice: string); procedure AddHeader(S: string; Posn: HeaderPosType); procedure AddStringEntryField(); function CreateBox: boolean; virtual; function GetLastChoice: word; function GetEditedString: string; procedure SetTimeOut(Delay: word); end; RadioButtons Methods. ===================== Declaration constructor Init(X1,Y1,X2,Y2: byte; var Colors: ColorSet; Options: longint; Orientation: HorizVerticalType; NrRows, NrCols: byte; CharExit: boolean; CommandHandler: pkGenlProc; PickOptions: word; Choices: MStringArrayPtr); Purpose Initialize this descendant of PickList which when drawn will display an arrangement of radio buttons. Description X1,Y1,X2,Y2 define the four corners of the active PickList window. They should be calculated based on the width of the choices, the orientation, the number of rows and number of columns of radio buttons. See DialogBox's CreateBox method for and example of calculating these window coordinates. Colors and Options are the normal parameters for windows. Orientation refers to the arrangement of radio buttons. Note this is a different type parameter from the one used in PickLists. The difference between rbHoriz and rbVertical is in whether the radio buttons scroll horizontally or vertically if there are more buttons than can be shown in the active window. NrRows and NrCols refers to the number of rows and columns of radio buttons and not to the number of character positions covered by the buttons. A button looks like this: ┌────────┐ │ Cancel │ └────────┘ The type of frame around the button may be changed by assigning a new value to ButtonFrame. The first character of the choice inside the button will be highlighted. CharExit defines whether the PickList search method used is PickCharSearch (CharExit = false) or PickCharExit (CharExit = true) as defined in OPRO manual page 4-199. CommandHandler and PickOptions are the same as you would use for a PickList. Choices is the string array that contains the labels that are placed in the radio buttons. Init assumes you will be using the standard CommandHandler, PickCommands, and makes some adjustments to it depending on the orientation. Since radio buttons are normally used in a dialog box that may have an entry field, there needs to be a way of moving from the entry field to the buttons and vice versa. For the horizontal arrangement cursor up is assigned to the exit command ccUser0. For the vertical arrangement cursor left is assigned to ccUser0. Declaration destructor Done; virtual Purpose To dispose of the RadioButtons object and restore PickCommands to the standard assignments. Description It does not dispose of the Choices array. Declaration procedure ItemString(Item: word; Mode: pkMode; var IType: pkItemType; var IString: string); virtual; Purpose This is a PickList ItemString method for returning the strings to be displayed in the PickList. Description In the case of RadioButtons this method is specially tailored to produce the radio button icons with the labels contained in the Choice array. The top and bottom rows of each button are separate items in the PickList display and are give the the pkProtected attribute. The area of highlighting for the selected choice is limited to exclude the frame charcters by using Flex attributes. Declaration procedure ProcessSelf; virtual Purpose To provide a seamless interface between the RadioButtons window field in an entry screen and other fields in the entry screen. Description This method overrides the standard PickList ProcessSelf. ccSelect and ccMouseSel are changed to ccDone so that the selection of a radio button choice will exit the entry screen Process. ccUser0 is changed to BackTab to move back to earlier entry screen fields. DialogBox Methods. ================== Declaration constructor Init(Orientation: HorizVerticalType; NumTextLines, TotalTextChars, NumChoices, TotalChoiceChars: word); Purpose Initialize internal data fields and allocate MStringArrays for storing lines of message text and choices. Description Orientation is either rbHoriz or rbVertical as explained above. NumTextLines is the maximum number of lines of text that you will want displayed as a message in the DialogBox. TotalTextChars = NumTextLines * AveLengthOfEachLine NumChoices is the number of radio buttons that you want. Each radio button displays one word from the ChoiceString. TotalChoiceChars = NumChoices * (AveLenghtOfEachChoice + 4) Since DialogBox uses a descendant of StringArrays for storing the lines of message Text to be displayed and the Choices, it is good practice to allocate your best estimate of the memory storage requirements through Init. However the StringArrays can reallocate if there is enough memory. Reallocation will fragment memory. For the EntryScreen field of DialogBox, Init uses the default ULRootColorSet, the default window options DefWindowOptions+wBordered, NrRows and NrCols equal 1, and CharExit equals false. Init will center the dialog box on the screen, truncating and limiting the number of rows of message lines to make everything fit in the screen space available. Declaration constructor InitDeluxe(X1, Y1: word; Options: longint; Colors: ColorSet; Orientation: HorizVerticalType; NrRows, NrCols: byte; CharExit: boolean; NumTextLines, TotalTextChars, NumChoices, TotalChoiceChars: word); Purpose To provide more flexibility that the default based Init in instantiating a DialogBox. Description X1 and Y1 define the upper left corner of the EntryScreen that is created by CreateBox. The actual position is adjusted so that the DialogBox will fit on the screen. The visible DialogBox is actually an EntryScreen. Values of 0,0 will cause the box to be centered on the screen. Values of ScreenWidth and ScreenHeight will always place the DialogBox in the lower right corner of the screen. Options define the window options used by the entry screen. Orientation is as explained above. NrRows, NrCols and CharExit are as explained under RadioButtons. The last 4 parameters are the same as for Init. Declaration destructor Done; virtual; Purpose Deallocate all memory associated with DialogBox. Description This includes memory for EntryScreen, RadioButtons, Text and Choice Arrays. Declaration procedure Clear; Purpose To set up the DialogBox for a new message and set of Choices. Description This resets the Message and Choice arrays by disposing of them and then reallocating at the same size. The EntryScreen is also disposed and all DialogBox data fields reinitialized. It is useful in those situations where you want to keep a DialogBox initialized and just keep sending new messages and choices. Using this technique limits heap fragmentation. Declaration function GetLastError: word; Purpose To return the last error recorded by DialogBox. Description Returns the error code and resets dlLastError to 0. Declaration procedure Process; Purpose To activate the DialogBox in preparation for obtaining user input. Description Process is a little different from other process methods in OPRO. It calls the method CreateBox described below to create the radio buttons (dlButtons^) and the EntryScreen (dlEntry^); add the text fields, the string entry field (if there is one) and the window field (dlButtons^). It then calls dlEntry^.Process and waits for an exit selection. Process uses the standard OPRO EntryCommands and PickCommands sets. If UseMouse is defined, as it is in ULDEFINE.INC, and a mouse is installed, the mouse is enabled. After an exit selection has been made Process also erases the DialogBox. If SetTimeOut has been used to set a delay time before the box is automatically erased, Process first calls Draw. Declaration procedure AddMessageString(Msg: string); Purpose To add message strings which will be displayed as TextFields in the entry screen to be created. Description You can add as many message strings as you want, but keep in mind that only those that will display on a full screen will be displayed and the lines will be truncated to fit in a full screen window with a border. The entry screen window is sized automatically as described under CreateBox. The maximum number of text lines that can be displayed is (ScreenHeight-5-NumberOfStringFieldLines). You do not have to add a message string if you just want the radio buttons. If you stay within the memory allocation specified in Init, then this is not likely to fail. Otherwise you should check GetLastError after adding. In the rbHoriz mode the message strings are centered. If you don't want them centered, just pad your strings with blanks. Declaration procedure AddChoice(Choice: string); Purpose To add exit choices that will be displayed in the radio button icons. Description Each Choice string is displayed as a label in a radio button icon. It is an error (epFatal+ecNoChoice) not to add a Choice string and the string may not be blank. If you stay within the memory allocation requirements specified in Init, this is not likely to fail. Otherwise you should check GetLastError after adding. Example AddChoice('Sometimes'); AddChoice('Always'); AddChoice('Never On Sunday'); This would result in the following radio buttons: ┌─────────────────┐┌─────────────────┐┌─────────────────┐ │ Sometimes ││ Always ││ Never On Sunday │ └─────────────────┘└─────────────────┘└─────────────────┘ Choice: 1 2 3 The labels are not centered to take advantage of the PickList character search procedures. Declaration procedure AddChoiceString(Choice: string); Purpose To add exit choices that will be displayed in the radio button icons. Description This works much like AddChoice but you can include several choices in the Choice string. Each word in the string is treated as a separate choice. Example AddChoiceString('Sometimes Always Never_On_Sunday'); Declaration procedure AddStringEntryField(Prompt: string; pRow, pCol: word; Picture: string; fRow, fCol: word; fWidth: byte; HelpIndex: word; EditSt: string); Purpose To add a string entry field to the DialogBox. Description The use of this method is exactly the same as AddStringField in OPRO. The positioning of the field is adjusted in CreateBox as necessary to center the field just above the radio buttons. pCol and fCol are adjusted to center the entry field inside the box in the rbHoriz mode; only their difference is significant. pRow and fRow are only used to determine whether the prompt and the field are on the same line or if not, which comes first. So the difference between pRow and fRow is the only thing that is significant. Declaration procedure AddHeader(S: string; Posn: HeaderPosType); Purpose To add a header on the frame of the DialogBox. Description Works just like the similar method in OPRO on the dlEntry^. It can fail because of insufficient memory. Declaration function GetLastChoice: word; Purpose Returns the number of the Choice that is selected. Description The exit Choices are numbered beginning with 1 in the sequence that they appear in the Choice string in AddChoiceString. This should be called after Process to get the exit selection. Declaration function GetEditedString: string; Purpose Returns the edited string if AddStringEntryField has been used. Description If no entry field has been added, it will always return a blank string. Declaration procedure SetTimeOut(Delay: word); Purpose Used to set a time out period (in seconds) for DialogBox. Description Sometimes it is useful to display a temporary message that is on the screen for a fixed length of time (Delay). If the user presses a key, the timeout feature is overridden and the DialogBox reverts to normal key and mouse operation. If the DialogBox exits because of timeout, the GetLastChoice will return a value of scTimeOut (presently = 99). Example if not MyDialog.Init(rbHoriz,1,78,2,20) then Exit; with MyDialog do begin AddMessageString('Test of timeout feature.'); AddChoiceString('Ok Cancel'); SetTimeOut(10); Process; Code := GetLastChoice; Done; end; If a key is not pressed within 10 seconds, Code = scTimeOut. If {Enter} is pressed, MyDialog is erased and Code = 1. If any other key is pressed, MyDialog reverts to normal operation. Declaration function CreateBox: boolean; virtual Purpose Initializes entry screen and radio buttons and adds fields. Description Normally CreateBox is called automatically by Process; however you may call it separately if you want to use non-default features. If CreateBox is called prior to Process, then it will not be called in Process. CreateBox sizes the entry screen window based on the messages, choices and entry field that are added. In the rbHoriz mode the radio buttons are centered at the bottom of the window. If an entry field is added, it is centered just above the radio buttons. In the rbVertical mode the radio buttons are at the right hand side of the window and the entry field is placed just below the lines of text. If all goes well, it returns true. When CreateBox exits, all objects are initialized and ready for a call to Process or Draw. CreateBox tries very hard to work with what you have given it to put the dialog box on the screen either in the center or as close as possible to the position you have defined using InitDeluxe. Comments or suggestions are welcome. I intend to add some other field types to DialogBox such as a Directory window.